home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Belgian Amiga Club - ADF Collection
/
BS1 part 34.zip
/
BS1 part 34
/
FredFish PD 308.adf
/
FReq
/
FReq.doc
< prev
next >
Wrap
Text File
|
1990-01-18
|
32KB
|
637 lines
Introduction
FReq is a general purpose file requester. It was written
as a result of my dissatisfaction with most of the file
requesters I am forced to use daily. FReq was designed to be
easy to use and fast.
You may ask yourself "What good is just a file requester
without an application program built around it?" Answer: FReq
was designed with a built-in REXX port allowing you to replace
the file requesters in your existing applications with FReq
(provided they also have a REXX port). Why would you want to
do this? I feel that once you have used FReq, you will wish
that all of your programs could use it.
Recognizing that not everyone currently has the ARexx
language (it will be part of the operating system in release
1.4 of AmigaDOS), I have provided a method of accessing FReq
without it. Please refer to the section Using FReq without
ARexx for a discussion of how to use FReq without the ARexx
language.
I am making FReq available to the general public without
charge to encourage its use. If you are a software developer,
please contact me to find out how you can incorporate FReq into
your own application.
Quick Run-Down of FReq's Features
+ User selects disks by volume name
+ Sorts directories and filenames separately
+ Filters ".info" files
+ Performs pattern matching
+ Can list all existing assignments
+ Displays file size
+ Displays file and directory dates
+ Displays file comments, protection bits, etc.
+ Stays resident in memory
+ Programmable using the ARexx language
+ Fast Operation. Able to scan hard disk directories
at greater than 60 entries per second.
Using FReq
First copy the file 'FReq' to your 'DEVS:' directory. The
example programs supplied with FReq assume that the 'FReq' file
is located in your 'DEVS:' directory.
With proper programming techniques it is not necessary to
pre-load FReq to use it. You may want to do this, however, to
prevent needing to load FReq when it's used the first time. If
you use FReq a lot, then it would be a good idea to add the
following line to your Startup-Sequence.
RUN >NIL: <NIL: DEVS:FReq >NIL: <NIL:
Note that nothing appears to happen after running FReq.
FReq does not open its window until a program calls for it.
The example program 'FReq.rexx' shows the proper way to call
FReq from within a REXX program.
The programs 'Startup.txed', 'Open.txed', and
'SaveAS.txed' can be used to replace the file requester in
MicroSmiths' TxEd Plus editor program. Each of these programs
contain comments explaining their use.
Quick Guide to Operating FReq
When FReq's window first opens, one of two possible items
are listed in the display window. If FReq is called upon with
the 'DisplayDef' option, the current directory is listed.
Otherwise all currently mounted disk volume names are listed.
Disk volume names may be identified by a small disk icon to the
left of each name.
The information FReq lists in its display window is color
coded. This document will assume you are using the default
preferences settings where color 1 is blue, color 2 is white,
color 3 is black, and color 4 is red. If you are using colors
different from these then substitute the colors you are using
for the ones listed above. In the 'Preferences' program, color
1 is on the far left and color 4 is on the right.
Filenames and directories are listed in FReq's display
window. The directories in the current path are sorted and
displayed first. Directories can be recognized by their red
color. Files are white in color and are sorted and displayed
after the directories.
To list the contents of a directory in the display window,
you simply "single-click" on the directory you want listed.
After doing so the chosen directory is added to the current
path and the contents of that directory is listed in the
display window. To get back the directory listed previously,
you can "single-click" on the "Parent" gadget located above and
to the left of the display window. Doing so will subtract the
current directory from the current path and then the "parent"
directory will be displayed.
Choosing a file is done in the same way that directories
are chosen. If you "single-click" on a filename, that name is
copied into the current filename box located just below the
display window. Note that the path and filename is not
returned to your calling program until the 'OK' button is
selected.
FReq's Menus
FReq has several menus which access many of its special
features. These menus are accessed in Intuition's normal
manner using the right mouse button. Detailed descriptions of
each menu and that menu's options are given below.
Project Menu - The only option under the Project menu is the
"About" option. Selecting "About" opens a window displaying
information about FReq. Some of the information displayed
includes the version number, the release date, and the public
REXX port name.
Display Menu - The display menu currently has three options:
"Name Only", "File Size", and "File Date". Selecting the file
size or date option causes the file size or date to display
beside the filename in the display window. Each of these menu
options also has an equivalent command key sequence. The key
sequence corresponding to each menu option is listed below.
Key Sequence Function Performed
Right-Amiga N Displays only the filename
Right-Amiga S Displays each file's size
Right-Amiga D Displays file and directory dates
Note that one of the Display Menu's options is always
activated. The Display Menu option which is currently active
is indicated by a check mark to the left of the menu option
itself.
Special Menu - The special menu has three options "Assigns",
"Display .info", and "File Status". Each control one of FReq's
special functions. The "Special" menu's options are described
below in detail.
Assigns - This menu option lists all of the logical assignments
currently defined in your system. Sometimes it is much easier
to locate a directory by its "Assigned" name rather than
locating it by its full path name. If you are unfamiliar with
logical assignments then refer to the AmigaDOS manual's Assign
command. Two examples of assignments which should always
be in existence are 'C:' (the directory containing all of the
CLI commands) and 'S:' (the directory containing your 'Startup-
Sequence' file and other script files).
Choosing a logical assignment from the display window
causes the complete path specification for that assignment to
be displayed in the "Current Path Gadget".
The "Assigns" menu option can also be performed by using
the 'Right-Amiga A' keyboard sequence.
Display .info - The "Display .info" menu option is one that can
be toggled on or off. FReq normally filters out (e.g. does not
list) any file with a suffix of '.info'. These ".info" files
are used by Workbench to display the icons associated with
files. For example, if your disk contains the two files
'Clock' and 'Clock.info', then the 'Clock' file is a program
which you can execute and the 'Clock.info' file contains the
picture of a clock that you will see in one of Workbench's
windows.
Normally, when choosing a file from an application
program, you will not need to see the ".info" files and that is
why FReq does not list them. If for some reason you do need to
see these files, then you can do so by setting the 'Display
.info' option "on". One reason you might need to access these
files, for instance, is if you are using an Icon Editor
program.
When this option is "on" there will be a check mark to the
left of this option in the menu.
The "Display .info" filter can be toggled "off" or "on" by
using the 'Right-Amiga I' command key sequence. In addition,
the REXX command 'DisplayInfo' can be used to set this filter
under program control.
File Status - The "File Status" menu option opens a window
displaying supplemental information on the currently selected
file. The information displayed includes the file's size,
date, protection bits, comment, and disk key. When you are
finished viewing a file's status, close the status window by
"single-clicking" on the close gadget located in the upper
left- hand corner of the window's border. Note that while the
status window is open, FReq becomes inoperable.
The file status function can be accessed from the keyboard
with the 'Right-Amiga F' command key sequence.
FReq's Gadgets
FReq has a number of gadgets represented by various icons
and boxes located within its window. The function of each
gadget is described in detail below.
Display Window Gadget - This gadget is the large black
rectangular box with a white border around it that occupies
most of FReq's main window. This area is where filenames,
directories, and disk volume names are displayed. A filename
can be selected, or a directory or disk volume's contents can
be listed simply by "single-clicking" on this gadget with the
mouse pointer over the desired name. File dates and sizes are
also displayed in this window by selecting the appropriate menu
function.
If you "double-click" on a filename in the display window,
this will have the same effect as "single-clicking" on the
filename and then selecting the "OK Gadget". "Double-Clicking"
on a volume or directory name produces the same effect as
"single-clicking".
Parent Gadget - The "Parent Gadget" is located just above and
to the left of the Display Window. The "Parent Gadget" causes
the parent of the current directory to be listed. If the
current directory is also the root directory of the disk being
accessed, then selecting the parent gadget lists the mounted
disk volume names.
If you have descended several levels of directories, you
can get back to the root directory of the currently selected
disk by holding down either SHIFT key while selecting this
gadget.
Volumes Gadget - The "Volumes Gadget" is located to the right
of the "Parent Gadget". Selecting the "Volumes Gadget" will
cause all of the mounted disk volume names to be listed in the
"Display Window".
Note that the disk volume names are also listed when you
select the "Parent Gadget" while at the root-level of a disk.
Scroll Bar - The scroll bar is located to the right of the
display window and is a long rectangular gadget. The scroll
bar lists the hidden filenames or directories. Since the
display window can only show up to 15 names at one time, a
given path with more than 15 entries cannot be fully displayed
at one time.
The size of the scroll bar corresponds directly to the
number of files in the current directory. For example, if
there are 30 files in the current directory then the scroll bar
will be half the size of its containing box; if there are 60
files then it will be one-forth the size, etc.
To scroll through the listing of files and directories,
place the mouse pointer over the scroll bar's knob and hold
down the left mouse button. Moving the mouse up and down
scrolls the display window to reveal the remaining files and
directories.
An alternate method to scrolling the display window is
"paging" it. You can display the next or previous page of
files and directories in the display window by "single-
clicking" with the mouse pointer directly below or above the
knob of the scroll gadget.
Arrow Gadgets - The arrow gadgets located directly below the
scroll gadget provide another method of scrolling the display
window. If the left mouse button is held down over an arrow
gadget, then the display window continues to scroll in the
direction of the arrow until the gadget is either released or
the end of the list of files is reached.
Holding down a shift key while selecting the up-arrow
gadget will move the display to the beginning of the file list.
Likewise, holding down a shift key while selecting the down-
arrow gadget will move to the extreme end of the file list.
Current Path Gadget - This gadget is the long rectangular box
located in the upper right corner of FReq's main window. Its
purpose is to display the complete path specification of the
directory listed in the display window. Normally the current
path automatically adjusts to reflect the volume and
directories chosen from the display window. You can, however,
manually adjust the path by "single-clicking" on the "Current
Path Gadget" and then typing in any valid AmigaDOS path
specification. After pressing the Return or Enter key, the
directory entered lists into the display window, provided a
valid path specification is given.
Note that this is a standard intuition string gadget and
once activated all of the standard editing command key
sequences will be available. These editing command sequences
are as follows:
Key Sequence Effect
Right-Amiga X Erases the entire line
Right-Amiga Q Undoes any changes made to the line
Shift-Right Arrow Moves cursor to the end of the line
Shift-Left Arrow Moves cursor to the start of the line
If the current path is entirely erased, leaving the
"Current Path Gadget" blank, the default path of the program
calling FReq is displayed.
Current Filename Gadget - This gadget is the long rectangular
gadget located immediately below the display window showing the
name of the currently selected file. If this gadget is blank,
then no file is selected.
The filename may be typed in from the keyboard or selected
by "single-clicking" on a file listed in the display window.
Note that the filename is not accepted until the "OK Gadget" is
selected. This feature will allow you, during a save
operation, to pick a filename from the display window similar
to the name you want to call your file, then just make minor
changes to it before selecting the "OK Gadget". For example,
if you want to save a file with the name 'My_Document2' and
there is already a file named 'My_Document' in the currently
listed directory, then you can choose 'My_Document' from the
display window and then simply edit that name adding the
character '2' to the end. Doing this can save a lot of typing.
The "Filename Gadget" is also a standard intuition string
gadget. The editing commands listed in the description of the
"Current Path Gadget" are available within this gadget as well.
Pattern Gadget - This is the small rectangular gadget located
below the "Current Filename Gadget". FReq provides complete
AmigaDOS pattern matching capabilities.
Normally, the "Pattern Gadget" contains the characters
'#?', a pattern specification meaning "match everything". You
can edit the pattern specification causing FReq to list only
those files and directories matching the specified pattern.
Some pattern specification examples are given below.
Pattern Effect
#? Lists all files and directories
#?.doc Lists only the files ending with '.doc'
c#? Lists only the files beginning with 'c'
#?x#? Lists only the files containing an 'x'
Keep in mind that it is possible to specify a pattern
resulting in no files or directories being listed. If this
happens, the screen flashes and an error message is displayed.
The editing commands of the "Pattern Gadget" are the same
as those listed for the "Current Path Gadget".
OK and CANCEL Gadgets - These gadgets are located in the lower
right corner of FReq's window and are identified by their
respective names. They are used to signal the program calling
FReq of your intentions. If the "OK Gadget" is selected, FReq
passes the complete path specification and filename back to the
calling program. If the "CANCEL Gadget" is selected, nothing
is passed back to the calling program except the message that
you have selected "Cancel".
Selecting the "OK Gadget" lets your program know that you
have selected a file and everything is "OK". Select the
"Cancel Gadget" if you wish to abort the current operation of
the calling program, such as the loading or saving of a file.
Close Window Gadget - Selecting this gadget is similar to
selecting the "CANCEL Gadget" with one important distinction.
This gadget causes FReq to close itself down and free up any
memory it was using. Normally FReq stays resident in memory
and remains there until the 'CloseDown' command is received at
its REXX port. Selecting the "Close Window Gadget" forces FReq
to close itself down immediately and should indicate a "Cancel"
condition to the calling program.
Keyboard Commands
FReq supports a number of keyboard commands. Note that if
one of the string gadgets is activated, all of the "key-
commands" are disabled until the "Return" or "Enter" key is
pressed. You can tell if a string gadget is activated by the
presence of a cursor within that gadget.
When FReq's main window first opens the "Current Filename"
string gadget is normally activated.
Below is a table listing the "key-commands" FReq supports.
Key Effect
f Activates the "Current Filename Gadget"
TAB Activates the "Current Filename Gadget"
d Activates the "Current Path Gadget"
p Activates the "Pattern Gadget"
RETURN Same as "Single-Clicking" the OK Gadget
ESC Same as "Single-Clicking" the CANCEL Gadget
In addition, FReq also has the following "Command Key"
sequences which may be used instead of their equivalent menu
bar selections. Below is the table of "Command Key" sequences.
Key Sequence Equivalent Menu Selection
Right-Amiga N Display Name Only
Right-Amiga S Display Size
Right-Amiga D Display Date
Right-Amiga A Display Assigns
Right-Amiga I Display ".info" files
Right-Amiga F File Status
The SHIFT key has a special meaning when used in
conjunction with either the "Parent Gadget" or the "Arrow
Gadgets". The special functions performed are listed in the
table below.
Command Effect
SHIFT + Parent Gadget List root directory of disk
SHIFT + Up Arrow Gadget Displays the top of the file list
SHIFT + Down Arrow Gadget Displays the end of file the list
The REXX Port
FReq has a REXX port named 'FileRequester' which can
receive commands issued by an ARexx program. The program
'FReq.rexx' supplied with FReq is a programming example of the
proper way to call FReq from within a REXX program.
The commands FReq currently supports are described in
detail below. Letter case is not important. Note that the
brackets denote an optional parameter.
DisplayDef - This command causes FReq to keep all of its
current settings including the path specification, filename,
and pattern matching specification. If the 'DisplayDef'
command is issued before the 'GetFileName' command, then FReq
will keep all of its previous settings when opening. Otherwise
these settings will be cleared.
Note that the 'DisplayDef' command must be issued each
time you call upon FReq and desire the default settings to be
maintained. This command is also required if you wish to
modify one of the default settings with one of the 'Set...'
commands listed below.
SetTitle [title] - This command will display title in the
"drag bar" of FReq's main window. 'Select a File' is the title
displayed by default. The title should be set to a meaningful
message telling the user why the file requester was called.
Some good examples are: 'Select a File to Load', 'Choose an
Archive to Extract', 'Select a Picture to View', etc.
SetPath [path] - This command sets the default path
specification to path. If this command is issued before the
'GetFileName' command, then path is displayed in the "Current
Path Gadget" and the contents of the directory specified by
path will be listed in the display window when FReq first
opens. If path is not a valid path specification then no files
are listed.
Note that you must also use the 'DisplayDef' command in
conjunction with this command in order for 'SetPath' to have
any effect. The 'SetPath' command sets the default path and
unless the 'DisplayDef' command is also issued, all the
defaults will be cleared when FReq opens.
SetPattern [pattern] - This command sets the pattern matching
specification to pattern. Normally it is good practice for the
pattern matching specification to be set by the user. This
matching specification applies to directories as well as files,
therefore, if you set a pattern using this command, the user
may not be able to fully navigate their directory tree because
some directories may not be displayed. The exception to this
rule is when you know ahead of time in which directory the user
needs to be looking. For example, if you want to list all of
the available libraries, then you could set the current path to
'LIBS:' and the pattern to '#?.library'.
Note that like the 'SetPath' command, you must also use
the 'DisplayDef' command in conjunction with 'SetPattern' in
order for this command to have any effect. The 'SetPattern'
command sets the default pattern matching specification and
unless the 'DisplayDef' command is also issued, all the
defaults will be cleared when FReq opens.
SetFileName [name] - This command sets the default filename to
name. No checking is done to determine whether or not name is
a valid filename.
Note that you must also use the 'DisplayDef' command in
order for this command to have any effect. The 'SetFileName'
command sets the default filename in the "Current Filename
Gadget" and unless the 'DisplayDef' command is also issued all
the defaults will be cleared when FReq opens.
GetFileName - This command asks FReq for a filename. It
returns the complete path specification and filename in the
'Result' variable of the calling REXX program. You should
first, however, check the value of the 'RC' return code
variable to find out if a filename was returned. If 'RC' is
equal to 0, then a path and filename was returned. Otherwise
no filename is returned and the 'Result' variable remains
unchanged. The possible values for 'RC' are listed below.
Value of RC Meaning of this return code
0 The user selected the OK gadget
1 The user selected the CANCEL gadget
2 The user selected the Close Window gadget
Note that most of FReq's other commands must be issued
before the 'GetFileName' command in order for them to work.
The 'GetFileName' command will pause your REXX program until
the user selects either OK, CANCEL, or Close Window.
DisplayInfo ON|OFF - This command turns "on" or "off" the
".info file" filtering feature of FReq. Normally this option
is set to "off" because there is usually no need to have these
files listed. Of course if you are using an Icon Editor you
may want to see the ".info" files.
CloseDown - The 'CloseDown' command will cause FReq to
terminate, freeing all memory that it was using. It is
normally a good idea to leave FReq resident in memory as this
will result in not having to load it in from disk each time it
is needed. However, if you need to save memory then you may
want to "CloseDown" FReq after using it.
Using FReq without ARexx
This first release of FReq is supplied in two versions.
To keep FReq as small as possible I decided to implement a
separate version which works without the ARexx language. The
version of FReq which doesn't require the ARexx language
(version b) is the file named 'FReq_v1b'. This version of FReq
sends the path specification and filename to the standard
output. Normally the "standard output" is the window from
which FReq was invoked. You can change this, however, by using
redirection when you execute FReq. For example, to send the
path specification and filename to a file in RAM: named
'FileName' execute FReq as follows:
FReq_v1b >RAM:FileName [ DEFAULT ]
Note that the "DEFAULT" key word is optional and you do
not type the bracket characters. When using version b of FReq,
the only option available is the "DEFAULT" option. This option
causes the default directory to list when FReq opens. Without
this option, the volume names list when FReq first opens.
Unlike version 1.0, version b of FReq clears itself out of
memory after each invocation. It would be a good idea to copy
'FReq_v1b' to the RAM disk if version b of FReq is being used.
Version b of FReq was primarily provided to allow
AmigaBASIC programmers to use FReq. You can call FReq from
within AmigaBASIC by using the dos.library's Execute()
function. Note that in order to use the Execute() function
from BASIC you must first issue the LIBRARY statement to open
'dos.library'. A detailed description of how to do this is
beyond the scope of this manual. Refer to the AmigaBASIC
manual's description of the CALL and LIBRARY statements for a
description of how to use external functions.
You can also use version b of FReq within your AmigaDOS
scripts. However, you will need some way of retrieving the
filename from the file you send it to. An example of doing
this with version 1.3 of AmigaDOS is given below.
FReq_v1b >ENV:FileName
GetEnv FileName
Error Codes
If you encounter an error during the execution of a REXX
program sending commands to FReq, you can determine what the
error is by examining the 'RC' variable. Below is a table of
possible error code returns and their meanings.
Error Code Meaning
50 Invalid Command. A command was sent to
FReq which it did not recognize.
51 Invalid Option. The option given after a
command is either not valid or an option
was required and not found.
99 Out of memory Error. This error can occur
whenever your computer gets low on memory.
Most of the time this error will cause FReq
to close down freeing any memory it used.